1. Introduction > 2. Mon premier projet > 3. Modèle > 4. Vue > 5. Liste de données > 6. Mapping objet/relationnel > 7. Contrôleurs > 8. Application > 9. Personnalisation

Chapitre 9 : Personnalisation

L'interface utilisateur générée par OpenXava est bonne pour la plupart des cas, mais parfois il est nécessaire de personnaliser une partie de l'interface (en créant vos propres éditeurs) ou créer complètement une interface utilisateur "maison" (à l'aide de vues JSP personnalisées).

Editeurs

Configuration des éditeurs

Vous avez vu que le niveau d'abstraction pour définir des vues est élevé : vous spécifiez les propriétés à afficher et comment les mettre en page, mais pas leur rendu. Pour définir un rendu de propriétés, OpenXava utilise des éditeurs.
Un éditeur indique l'apparence d'une propriété. Il est constitué d'une définition XML ainsi qu'un fragment JSP. Pour affiner le comportement des éditeurs d'OpenXava ou pour ajouter des éditeurs personnalisés, vous devez créer dans le dossier xava de votre projet un fichier appelé editors.xml. Ce fichier ressemble à ceci :

<?xml version = "1.0" encoding = "ISO-8859-1"?>
 
<!DOCTYPE editors SYSTEM "dtds/editors.dtd">
 
<editors>
    <editor .../> ...
</editors>

Il contient simplement la définition d'un groupe d'éditeurs et la définition d'un éditeur est spécifiée ainsi :

<editor
    name="name"                        <!--  1  Depuis v2.1.3 -->
    url="url"                          <!--  2 -->
    format="true|false"                <!--  3 -->
    depends-stereotypes="stereotypes"  <!--  4 -->
    depends-properties="properties"    <!--  5 -->
    frame="true|false"                 <!--  6 -->
    always-reload="true|false"         <!--  7  Depuis v3.1.2 -->
    composite="true|false"             <!--  8  Depuis v3.1.3 -->
>
    <property ... /> ...               <!--  9 -->
    <formatter ... />                  <!-- 10 -->
    <list-formatter ... />             <!-- 11  Depuis v3.1.4 -->
    <for-stereotype ... /> ...         <!-- 12 -->
    <for-type ... /> ...               <!-- 13 -->
    <for-model-property ... /> ...     <!-- 14 -->
    <for-reference ... /> ...          <!-- 15  Depuis v3.1.3 -->
    <for-collection ... /> ...         <!-- 16  Depuis v3.1.3 -->
    <for-valid-values />               <!-- 17  Depuis v2.1.2 -->
    <for-references />                 <!-- 18  Depuis v3.1.3 -->
    <for-collections />                <!-- 19  Depuis v3.1.3 -->
    <for-element-collections />        <!-- 20  Depuis v5.0 -->
    <for-tabs />                       <!-- 21  Depuis v4.6 -->
</editor>

1. name (optionnel): (Depuis v2.1.3) (Please, translate this to French) Name for referencing to this editor from other places, like @Editor from a JPA entity or <reference-view ... editor=/> from a XML component.
2. url (obligatoire). URL du fragment JSP qui implémente l'éditeur
3. format (optionnel). Si la valeur est true (vrai), OpenXava a la responsabilité de formater la données de HTML à Java et vice-versa. Si la valeur est false (faux), la responsabilité de ce formatage incombe à l'éditeur lui-même (généralement en récupérant les données de la requête - objet request de la page JSP - et en l'assignant à l'objet de type org.openxava.view.View et vice-versa). Par défaut, la valeur est true (vrai).
4. depends-stereotypes (optionnel). Liste de stéréotypes (séparés par des virgules) dont dépend cet éditeur. Si dans la même vue se trouvent certains de ce type d'éditeurs pour ces stéréotypes, ils induiront un événement de changement de valeur lorsque leur valeur change.
5. depends-properties (optionnel). Liste de propriétés (séparés par des virgules) dont dépend cet éditeur. Si dans la même vue se trouvent certains de ce type d'éditeurs pour ces propriétés, ils induiront un événement de changement de valeur lorsque leur valeur change.
6. frame (optionnel). Si la valeur est true (vrai), l'éditeur sera affiché à l'intérieur d'un cadre (frame). Par défaut la valeur est false (faux). Ceci est utile surtout pour de grands éditeurs (plus d'une ligne) qui sont plus élégants de cette manière.
7. always-reload (optionnel): (Depuis v3.1.2) (Please, translate this to French) If true, this editor is reloaded always (each time a user executes an action or he does any other request to the application). When false the editor is reloaded only when the data it represents has been changed. The default is false.
8. composite (optionnel): (Depuis v3.1.3) (Please, translate this to French) A composite editor is made up by several other editors; it receives a View object that represents a subview. The default is false.
9. property (plusieurs, optionnel). Permet d'attribuer des valeurs dans l'éditeur. De cette manière, vous pouvez configurer votre éditeur et l'utiliser plusieurs fois dans des contextes différents.
10. formatter (un seul, optionnel). Classe Java qui défini la conversion des valeurs de Java à HTML et de HTML vers Java.
11. list-formatter (un seul, optionnel): (Depuis v3.1.4) Classe Java qui défini la conversion des valeurs de Java à HTML in list mode.
12. for-stereotype (l'un de ceux-là obligatoire, mais un seul). Associe cet éditeur à un stéréotype. L'ordre de préférence est celui-ci : d'abord la propriété, puis le stéréotype et enfin le type.
13. for-type (l'un de ceux-là obligatoire, mais un seul). Associe cet éditeur à un type. L'ordre de préférence est celui-ci : d'abord la propriété, puis le stéréotype et enfin le type.
14. for-model-property (l'un de ceux-là obligatoire, mais un seul). Associe cet éditeur à une propriété concrète d'un modèle. L'ordre de préférence est celui-ci : d'abord la propriété, puis le stéréotype et enfin le type.
15. for-reference (several, optional): (Depuis v3.1.3) (Please, translate this to French) This editor will be used for the references to the specified model.
16. for-collection (several, optional): (Depuis v3.1.3) (Please, translate this to French) This editor will be used for the collections of objects of the specified model.
17. for-valid-values (one, optional): (Depuis v2.1.2) (Please, translate this to French) This will be the default editor for enum and <valid-values/>.
18. for-references (one, optional): (Depuis v3.1.3) (Please, translate this to French) This will be the default editor for references.
19. for-collections (one, optional): (Depuis v3.1.3) (Please, translate this to French) This will be the default editor for collections.
20. for-element-collections (one, optional): (Depuis v5.0) (Please, translate this to French) This will be the default editor for element collections.
21. for-tabs (one, optional): (Depuis v4.6) (Please, translate this to French) This will be the default editor for tabs.

Voyons un exemple de définition d'un éditeur. Cet exemple est un éditeur qui est livré avec OpenXava, mais est un bon exemple pour apprendre comment réaliser vos éditeurs personnalisés.

<editor url="textEditor.jsp">
    <for-type type="java.lang.String"/>
    <for-type type="java.math.BigDecimal"/>
    <for-type type="int"/>
    <for-type type="java.lang.Integer"/>
    <for-type type="long"/>
    <for-type type="java.lang.Long"/>
</editor>

Voici un groupe de types basiques assignés à l'éditeur textEditor.jsp (que vous trouverez dans le dossier web/xava/editors). Le code JSP de cet éditeur est le suivant :

<%@ page import="org.openxava.model.meta.MetaProperty" %>
 
<%
String propertyKey = request.getParameter("propertyKey");                            // 1
MetaProperty p = (MetaProperty) request.getAttribute(propertyKey);                   // 2
String fvalue = (String) request.getAttribute(propertyKey + ".fvalue");              // 3
String align = p.isNumber()?"right":"left";                                          // 4
boolean editable="true".equals(request.getParameter("editable"));                    // 5
String disabled=editable?"":"disabled";                                              // 5
String script = request.getParameter("script");                                      // 6
boolean label = org.openxava.util.XavaPreferences.getInstance().isReadOnlyAsLabel();
if (editable || !label) {                                                            // 5
%>
<input id="<%=propertyKey%>" name="<%=propertyKey%>" class=editor                  <!-- 1 -->
    type="text"
    tabindex="1"                                                                   <!-- 7 -->
    title="<%=p.getDescription(request)%>"
    align='<%=align%>'                                                             <!-- 4 -->
    maxlength="<%=p.getSize()%>"
    size="<%=p.getSize()%>"
    value="<%=fvalue%>"                                                            <!-- 3 -->
    <%=disabled%>                                                                  <!-- 5 -->
    <%=script%>                                                                    <!-- 6 -->
    />
<%
} else {
%>
<%=fvalue%>&nbsp;
<%
}
%>
<% if (!editable) { %>
    <input type="hidden" name="<%=propertyKey%>" value="<%=fvalue%>">
<% } %>

Un éditeur JSP reçoit un ensemble de paramètres et peut accéder aux attributs qui lui permet d'être configuré de manière appropriée par rapport à son interaction avec OpenXava. Tout d'abord, vous pouvez remarquer l'utilisation du paramètre propertyKey qui est utilisé comme identifiant de la requête et identifiant HTML (1). A partir de cet identifiant, il est possible d'accéder à la méta-propriété par l'objet de type MetaProperty (2) (celui qui contient les méta-informations de la propriété en cours d'édition). L'attribut fvalue contient la valeur déjà formatée et prête pour l'affichage. Les attributs align (4) et editable(5) sont également déduites. Enfin, vous devez charger un fragment de code Javascript (6) pour l'insérer dans l'éditeur. (Please, translate the next sentence to French) You have to specify tabindex="1" (7) in order that the editors would be in the correct tab order (new in v4.5.1).
Même s'il est simple de créer un éditeur directement avec la technologie JSP, il n'est pas courant de le faire. En fait, il est plus pratiques de configurer des fragments JSP existants. Par exemple, vous pouvez écrire ceci dans votre fichier xava/editors.xml :

<editor url="textEditor.jsp">
    <formatter class="org.openxava.formatters.UpperCaseFormatter"/>
    <for-type type="java.lang.String"/>
</editor>

Ici, vous remplacez le comportement d'OpenXava pour traiter les propriétés de type String afin que toutes les chaînes de caractères soient affichées et acceptées en lettres capitales. Le code du formateur est le suivant :

package org.openxava.formatters;
 
import javax.servlet.http.*;
 
/**
 * @author Javier Paniza
 */
 
public class UpperCaseFormatter implements IFormatter {                // 1
 
    public String format(HttpServletRequest request, Object string) {  // 2
        return string==null?"":string.toString().toUpperCase();
    }
 
    public Object parse(HttpServletRequest request, String string) {   // 3
        return string==null?"":string.toString().toUpperCase();
    }
 
}

Un formateur doit implémenter l'interface IFormatter (1). Ceci force la définition de la méthode format() (2) qui convertit la valeur de la propriété (n'importe quel objet Java) vers une chaîne de caractères insérée dans le code HTML. De même, la méthode parse() (3) doit aussi être définie afin de prendre en charge la conversion de la chaîne de caractères reçue via l'envoi du formulaire HTML en un objet compatible avec le type de la propriété.
(Please, translate this to French) Also we can set a specific formatter to display information in list mode (New in v3.1.4) through list-formatter. The formatter assigned to this attribute designates the form in which the information is displayed at list mode without affected detail mode. This formatter must implement IFormatter but unlike the previous one only needs to implement format(). If list-formatter is not specified then formatter is used for list mode too.

Editeurs multi-valués

Définir un éditeur capable de traiter plusieurs valeurs n'est pas très différent d'un éditeur mono-valeur. Par exemple, si vous souhaitez définir un stéréotype REGIONS qui permet à l'utilisateur de choisir plusieurs régions dans une seule propriété, définie ainsi :

@Stereotype("REGIONS")
private String [] regions;

vous devrez ajouter l'entrée suivante dans votre fichier stereotype-type-default.xml :

<for stereotype="REGIONS" type="String []"/>

puis définir votre éditeur dans le fichier editors.xml :

<editor url="regionsEditor.jsp">                                                <!-- 1 -->
    <property name="regionsCount" value="3"/>                                   <!-- 2 -->
    <formatter class="org.openxava.formatters.MultipleValuesByPassFormatter"/>  <!-- 3 -->
    <for-stereotype stereotype="REGIONS"/>
</editor>

Le fragment JSP regionsEditor.jsp (1) s'occupe du rendu de l'éditeur. En outre, les propriétés qui doivent être envoyées comme paramètres de requêtes sont déclarées (2). Finalement, le formateur doit implémenter l'interface IMultipleValuesFormatter, qui est similaire à IFormatter mais qui utilise un objet de type String[] à la place d'un objet String. Dans notre cas, nous utilisons un formateur générique qui opère simplement un filtre passe-tout. Il faut encore écrire le fragment JSP regionsEditor.jsp :

<%@ page import="java.util.Collection" %>
<%@ page import="java.util.Collections" %>
<%@ page import="java.util.Arrays" %>
<%@ page import="org.openxava.util.Labels" %>
 
<jsp:useBean id="style" class="org.openxava.web.style.Style" scope="request"/>
 
<%
String propertyKey = request.getParameter("propertyKey");
String [] fvalues = (String []) request.getAttribute(propertyKey + ".fvalue");  // 1
boolean editable="true".equals(request.getParameter("editable"));
String disabled=editable?"":"disabled";
String script = request.getParameter("script");
boolean label = org.openxava.util.XavaPreferences.getInstance().isReadOnlyAsLabel();
if (editable || !label) {
    String sregionsCount = request.getParameter("regionsCount");
    int regionsCount = sregionsCount == null?5:Integer.parseInt(sregionsCount);
    Collection regions = fvalues==null?Collections.EMPTY_LIST:Arrays.asList(fvalues);
%>
<select id="<%=propertyKey%>" name="<%=propertyKey%>" multiple="multiple"
    class=<%=style.getEditor()%>
    <%=disabled%>
    <%=script%>>
    <%
    for (int i=1; i<regionsCount+1; i++) {
        String selected = regions.contains(Integer.toString(i))?"selected":"";
    %>
    <option
        value="<%=i%>" <%=selected%>>
        <%=Labels.get("regions." + i, request.getLocale())%>
    </option>
    <%
    }
    %>
</select>
<%
}
else {
    for (int i=0; i<fvalues.length; i++) {
%>
<%=Labels.get("regions." + fvalues[i], request.getLocale())%>
<%
    }
}
%>
 
<%
if (!editable) {
    for (int i=0; i<fvalues.length; i++) {
%>
        <input type="hidden" name="<%=propertyKey%>" value="<%=fvalues[i]%>">
<%
    }
}
%>

Comme vous le constatez à la lecture du code ci-dessus, cela ressemble à un éditeur mono-valeur. La principale différence provient du fait que la valeur formatée est un tableau de chaînes de caractères (String[]) à la place d'une chaîne simple (String).
(Please, translate this to French) As alternative, you can define the above editor using checkboxes (new in v4.9), as following:

<%@ page import="java.util.Collection" %>
<%@ page import="java.util.Collections" %>
<%@ page import="java.util.Arrays" %>
<%@ page import="org.openxava.util.Labels" %>
 
<jsp:useBean id="style" class="org.openxava.web.style.Style" scope="request"/>
 
<%
String propertyKey = request.getParameter("propertyKey");
String [] fvalues = (String []) request.getAttribute(propertyKey + ".fvalue");
boolean editable="true".equals(request.getParameter("editable"));
String disabled=editable?"":"disabled";
String script = request.getParameter("script");
boolean label = org.openxava.util.XavaPreferences.getInstance().isReadOnlyAsLabel();
if (editable || !label) {
    String sregionsCount = request.getParameter("regionsCount");
    int regionsCount = sregionsCount == null?5:Integer.parseInt(sregionsCount);
    Collection regions = fvalues==null?Collections.EMPTY_LIST:Arrays.asList(fvalues);
    for (int i=1; i<regionsCount+1; i++) {
        String checked = regions.contains(Integer.toString(i))?"checked":"";
    %>
        <input name="<%=propertyKey%>" type="checkbox" class="<%=style.getEditor()%>"
                tabindex="1"
                value="<%=i%>"
                <%=checked%>
                <%=disabled%>
                <%=script%>
        />
        <%=Labels.get("regions." + i, request.getLocale())%>
    <%
    }
}
else {
    for (int i=0; i<fvalues.length; i++) {
%>
<%=Labels.get("regions." + fvalues[i], request.getLocale())%>
<%
    }
}
%>
 
<%
if (!editable) {
    for (int i=0; i<fvalues.length; i++) {
%>
        <input type="hidden" name="<%=propertyKey%>" value="<%=fvalues[i]%>">
<%
    }
}
%>

Editors for references (new in v3.1.3)

Please, translate this section to French
By default references are displayed with a detail view, but you can create your own editor for references. For example, you can write this in the editors.xml file of your application:

<editor url="colorEditor.jsp">
    <for-reference model="Color"/>
</editor>
 

With the above code you say that any reference to Color entity must be displayed and edited using colorEditor.jsp (for using an editor only for a concrete reference in a concrete entity look at Choosing an editor section in chapter 4).
Here the code for colorEditor.jsp:

<%@page import="java.util.Iterator"%>
<%@page import="org.openxava.test.model.Color"%><%
 
String propertyKey = request.getParameter("propertyKey"); // Id of the key property of the reference (1)
Object value = request.getAttribute(propertyKey + ".value"); // You can use propertyKey + ".value" (2)
if (value == null) value = 0;
 
for (Iterator it = Color.findAll().iterator(); it.hasNext(); ) {
    Color color = (Color) it.next();
    String checked = value.equals(color.getNumber())?"checked='checked'":"";
%>
<span style="font-weight: bold; color: #<%=color.getHexValue()%>; vertical-align: bottom">
    <input name="<%=propertyKey%>" value="<%=color.getNumber()%>" type="radio" <%=checked%>/> <!-- (3) -->
    <%=color.getName()%>
</span>
<%
}
%>

The parameter "propertyKey" (1) give you the id for the key property of the reference. You can use it to name the HTML input element (3) or to get the its current value (2). The list of parameters to be used in a reference editor is:

1. referenceKey: Unique identifier OX gives to this reference.
2. propertyKey: Unique identifier of the property that is the key of the reference.
3. editable: If the reference must be editable by the user.
4. viewObject: The session object name of the subview that represents this reference. Only applies to composite editors.
5. propertyPrefix: Prefix used for giving name to editors for properties. Only applies to composite editors.

Moreover, you can define the way display all references by default for your entire application, using <for-references/>. Edit your editors.xml and add:

<editor name="MyReference" url="myReferenceEditor.jsp" frame="true" composite="true">
    <for-references/>
</editor>

Since you have marked the editor with <for-references/> now all the references in your application will be displayed using your myReferenceEditor.jsp. This is a simple way to customize the behaviour of OpenXava UI generator.

Editors for collections (new in v3.1.3)

Please, translate this section to French
By default collections are displayed with a tabular data list, but you can create your own editor for collections. For example, you can write this in the editors.xml file of your application:

<editor url="blogCommentsEditor.jsp">
    <for-collection model="BlogComment"/>
</editor>

With the above code you say that any collection of BlogComment entities must be displayed and edited using blogCommentsEditor.jsp (for using an editor only for a concrete collection in a concrete entity look at Choosing an editor section in chapter 4). <for-collection /> works for @OneToMany/@ManyToMany and @ElementCollection collections.
Here the code for blogCommentsEditor.jsp:

<jsp:include page="collectionEditor.jsp">
    <jsp:param name="listEditor" value="blogCommentsListEditor.jsp"/>
</jsp:include>

This is a typical way to create a collection editor, you call to collectionEditor.jsp (the default OpenXava editor for collections) sending as listEditor argument a JSP that contains the editor for the list part. In this way you have all the actions and default behaviour for collections for free, so you only have to do the rendering of the list.
The blogCommentsListEditor.jsp is:

<%@ include file="../imports.jsp"%>
 
<%@page import="org.openxava.view.View"%>
<%@page import="org.openxava.model.MapFacade"%>
<%@page import="org.openxava.test.model.Blog"%>
<%@page import="org.openxava.test.model.BlogComment"%>
<%@page import="java.util.Iterator"%>
<%@page import="java.util.Map"%>
<%@page import="java.text.DateFormat"%>
<%@page import="org.openxava.util.Locales"%>
<%@page import="org.openxava.util.Is"%>
 
<jsp:useBean id="context" class="org.openxava.controller.ModuleContext" scope="session"/>
 
<%
String viewObject = request.getParameter("viewObject"); // Id to access to the view object of the collection
View collectionView = (View) context.get(request, viewObject); // We get the collection view by means of context
View rootView = collectionView.getRoot(); // In this case we use the root view, the view of Blog
Map key = rootView.getKeyValues();
if (Is.empty(key)) {
%>
There are no comments
<%
} else { // If the key has value, then we render the collection of comments
 
Blog blog = (Blog) MapFacade.findEntity("Blog", key);
String action = request.getParameter("rowAction"); // rowAction is the action to edit or view each element
String actionArgv = ",viewObject=" + viewObject;
%>
 
These are the comments:<br/>
<%
DateFormat df = DateFormat.getDateInstance(DateFormat.SHORT, Locales.getCurrent());
int f=0;
for (Iterator it = blog.getComments().iterator(); it.hasNext(); f++) {
    BlogComment comment = (BlogComment) it.next();
%>
<i><b><big>Comment at <%=df.format(comment.getDate())%></big></b></i>
<xava:action action='<%=action%>' argv='<%="row=" + f + actionArgv%>'/>
<p>
<i><%=comment.getBody()%></i>
</p>
<hr/>
<%
}
 
}
%>

This editor draw the blog comments as simple texts with a date as header.
The list of parameters to be used in a list editor for collections is:

1. collectionName: The name of collection as you write it in your entity.
2. viewObject: The session object name of the subview that represents this collection.
3. rowAction: The qualified action name (Controller.action as in controllers.xml) to execute in each element in order to view or edit it.

Of course, you can create your collection editor from scratch, without using collectionEditor.jsp. In this case you have to write the whole user interface for the collection. Look an example in carriersNamesEditor.jsp:

<%@page import="org.openxava.view.View"%>
<%@page import="org.openxava.model.MapFacade"%>
<%@page import="org.openxava.test.model.Carrier"%>
<%@page import="java.util.Iterator"%>
 
<jsp:useBean id="context" class="org.openxava.controller.ModuleContext" scope="session"/>
 
<%
String viewObject = request.getParameter("viewObject"); // viewObject is the id of the view of the parent object
View view = (View) context.get(request, viewObject); // view is the view of Carrier, the parent of the collection
Carrier carrier = (Carrier) MapFacade.findEntity("Carrier", view.getKeyValues());
%>
The fellows of <%=carrier.getName()%> are:<br>
<ul>
<%
for (Iterator it = carrier.getFellowCarriers().iterator(); it.hasNext(); ) {
    Carrier fellow = (Carrier) it.next();
%>
<li><%=fellow.getName()%></li>
<%
}
%>
</ul>

In this case you write the code for render the complete collection, if you wish to have some actions for working with the collection you must put it yourself. Beware, because viewObject here is the view of the object that contains the collection, not the view of the collection itself.
The list of parameters to be used in an editor for collections is:

1. collectionName: The name of collection as you write it in your entity.
2. viewObject: The session object name of the view or subview that represents the parent object of this collection.

Moreover, you can define the way all collections are displayed by default for your entire application, using <for-collections/> for @OneToMany/@ManyToMany collections and <for-element-collections/> (new in v5.0) for @ElementCollection. Edit your editors.xml and add:

<editor name="MyCollection" url="myCollectionEditor.jsp">
 <for-collections/>
</editor>
 
<editor name="MyElementCollection" url="myElementCollectionEditor.jsp">
 <for-element-collections/> <!-- New in v5.0 -->
</editor>

Now all @OneToMany/@ManyToMany collections in your application will be displayed using your myCollectionEditor.jsp and all @ElementCollection collections using your myElementCollectionEditor.jsp.

Editors for tabs (list mode) (new in v4.6)

Please, translate this section to French
By default tabular data (the data shown in list mode) is displayed with a list, but you can create your own editor for list mode. For example, you can write this in the editors.xml file of your application:

<editor url="corporationEmployeeListEditor.jsp">
  <for-tab model="CorporationEmployee"/>
</editor>

With the above code you say that all tabs (all the lists) for CorporationEmployee entity must be displayed and edited using corporationEmployeeListEditor.jsp (for using an editor only for a concrete tab of an entity look at Choosing an editor section in chapter 5).
Here is the code for corporationEmployeeListEditor.jsp:

<%@ include file="../imports.jsp"%>
 
<jsp:useBean id="context" class="org.openxava.controller.ModuleContext" scope="session"/>
 
<%
String tabObject = request.getParameter("tabObject");
tabObject = (tabObject == null || tabObject.equals(""))?"xava_tab":tabObject;
org.openxava.tab.Tab tab = (org.openxava.tab.Tab) context.get(request, tabObject);
String condition = tab.getBaseCondition()==null?"":tab.getBaseCondition();
String all = condition.equals("")?"selected":"";
String low = condition.contains("<=")?"selected":"";
String high = condition.contains(">")?"selected":"";
String action="openxava.executeAction('OpenXavaTest', 'CorporationEmployee'," +
    "false, false, 'CorporationEmployee.filter', 'segment='+this.value)";
%>
 
<select name="<xava:id name='chooseSegment'/>" style='margin-bottom: 6px' onchange=
    "<%=action%>">
    <option value="all" <%=all%>>All employees</option>
    <option value="low" <%=low%>>Low salary employees</option>
    <option value="high" <%=high%>>High salary employees</option>
</select>
 
<jsp:include page="listEditor.jsp"/>

Note that this editor includes listEditor.jsp at the end. listEditor.jsp is the default editor for list mode, so in this case we only refine the standard list adding a combo to choose a custom filter. However, you can create your own list editor from scratch, for example, the following editor, customerCardListEditor.jsp, shows a list customer as a row of cards:

<%@ include file="../imports.jsp"%>
 
<jsp:useBean id="context" class="org.openxava.controller.ModuleContext" scope="session"/>
 
<%
String collection = request.getParameter("collection");
String id = "list";
String collectionArgv = "";
String prefix = "";
String tabObject = request.getParameter("tabObject");
tabObject = (tabObject == null || tabObject.equals(""))?"xava_tab":tabObject;
if (collection != null && !collection.equals("")) {
    id = collection;
    collectionArgv=",collection="+collection;
    prefix = tabObject + "_";
}
org.openxava.tab.Tab tab = (org.openxava.tab.Tab) context.get(request, tabObject);
org.openxava.tab.impl.IXTableModel model = tab.getTableModel();
for (int r=tab.getInitialIndex(); r<model.getRowCount() && r < tab.getFinalIndex(); r++) {
%>
    <xava:link action="List.viewDetail"><div
      style="border: 2px solid rgb(130, 143, 149); display: inline-block; padding: 10px; margin-bottom: 10px;">
    <h4><%=model.getValueAt(r, 1)%>(<%=model.getValueAt(r, 0)%>)</h4>
    <%=model.getValueAt(r, 2)%><br/>
    <%=model.getValueAt(r, 3)%> (<%=model.getValueAt(r, 4)%>)
    </div></xava:link>
<%
}
%>

Moreover, you can define the way all the lists are displayed by default for your entire application, using <for-tabs/>. Edit your editors.xml and add:

<editor name="MyList" url="myListEditor.jsp">
  <for-tabs/>
</editor>

Since you have marked the editor with <for-tabs/> now all the tabs in your application will be displayed using your myListEditor.jsp. This is a simple way to customize the behaviour of the OpenXava UI generator.

JavaScript in editors

Please, translate this section to French

Since v4m3

If you need custom or third-party JavaScript functions to be used from your editor, you cannot include them in the JSP directly, because the editor markup is loaded via AJAX. Instead you have to put your functions in an JS file and put it in the web/xava/editors/js folder of your project. All the JavaScript there is loaded automatically.
That is, if you need to use a JavaScript function f() from your editor, just as following:

<input ... onclick="f()"/>

You have to define the f() function in a JS file. Create a file called myEditor.js (or whatever name you want), and put it in web/xava/editors/js folder. The content of that file can be:

function f() {
  alert("Hello. It's f()");
}

On the other hand. If you need JavaScript initialization logic for your editor, you cannot use onload event or equivalent, because the editor markup is loaded via AJAX, so no page loading is produced. You have to register your initialization code in OpenXava. You can do it in your myEditor.js file (or another file in web/xava/editors/js), as following:

openxava.addEditorInitFunction(function() {
  /*
  Here your initialization code for your editor.
  That is the things your usually put in onload JavaScript event
  or $(function() { ... }) of jQuery
  */
  ...
});

You see how using openxava.addEditorInitFunction() to register an initialization function. The onload JavaScript event or ready() event of jQuery does not work, because no page is loaded, instead the editor is generated in the server, loaded via AJAX and inserted in the already displayed page.
Since v4.8.1 you can also define a destroy function for your editor in your myEditor.js file:

openxava.addEditorDestroyFunction(function() { // New in v4.8.1
/*
Here the destroy code for your editor.
This is to free resources obtained by the editor.
*/
...
});

Until v4m2

You have to put all the JavaScript code for all your editors in custom-editors.js in the folder web/xava/js. This technique is still supported though deprecated.

Until 3.0.x

No AJAX is used, so the JavaScript code can be included directly in the JSP for the editor.

Editeurs personnalisés et stéréotypes pour listes déroulantes

Dans votre application, vous pourriez avoir besoin de propriétés simples nécessitant d'être affichées comme des listes déroulantes après avoir été alimentées par des valeurs de la base de donnée. Prenons un exemple avec les propriétés d'entités suivantes :

@Stereotype("FAMILY")
private int familyNumber;
 
@Stereotype("SUBFAMILY")
private int subfamilyNumber;

Dans le fichier editors.xml, les entrées suivantes sont définies :

<editor url="descriptionsEditor.jsp">                                           <!-- 10 -->
    <property name="model" value="Family"/>                                     <!--  1 -->
    <property name="keyProperty" value="number"/>                               <!--  2 -->
    <property name="descriptionProperty" value="description"/>                  <!--  3 -->
    <property name="orderByKey" value="true"/>                                  <!--  4 -->
    <property name="readOnlyAsLabel" value="true"/>                             <!--  5 -->
    <for-stereotype stereotype="FAMILY"/>                                       <!-- 11 -->
</editor>
 
<!-- Il est possible de spécifier des dépendances vers des stéréotype ou des propriétés -->
<editor url="descriptionsEditor.jsp"                                            <!-- 10 -->
    depends-stereotypes="FAMILY">                                               <!-- 12 -->
<!--
<editor url="descriptionsEditor.jsp" depends-properties="familyNumber">         <!-- 13 -->
-->
    <property name="model" value="Subfamily"/>                                  <!--  1 -->
    <property name="keyProperty" value="number"/>                               <!--  2 -->
    <property name="descriptionProperties" value="number, description"/>        <!--  3 -->
    <property name="condition" value="${familyNumber} = ?"/>                    <!--  6 -->
    <property name="parameterValuesStereotypes" value="FAMILY"/>                <!--  7 -->
    <!--
    <property name="parameterValuesProperties" value="familyNumber"/>           <!--  8 -->
    -->
    <property name="descriptionsFormatter"                                      <!--  9 -->
        value="org.openxava.test.formatters.FamilyDescriptionsFormatter"/>
    <for-stereotype stereotype="SUBFAMILY"/>                                    <!-- 11 -->
</editor>

Lorsque vous affichez la vue avec ces deux propriétés (familyNumber - numéro de catégorie - et subFamilyNumber - numéro de sous-catégorie), OpenXava affiche une liste déroulante pour chaque propriété. La liste de catégories est remplie avec les données de toutes les catégories et la liste de sous-catégories est vide. Lorsqu'un utilisateur choisi une catégorie, la liste de sous-catégories est remplie avec les données des sous-catégories associées avec la catégorie sélectionnée.
Afin d'arriver à cet effet, vous devez assigner aux stéréotypes (FAMILY et SUBFAMILIY dans ce cas (11)) l'éditeur descriptionsEditor.jsp (10) et le configurer en lui assignant des valeurs à ses propriétés. Voici quelques propriétés de cet éditeur que vous pouvez définir :

1. model : Le modèle à partir duquel obtenir les données. Cela peut être le nom d'une entité (par exemple Invoice - facture) ou le nom d'un modèle utilisé pour une collection embarquée (Invoice.invoiceDetail - Facture.détailFacture).
2. keyProperty ou keyProperties : La ou les propriété(s) clé utilisée(s) pour obtenir la valeur de la propriété courante. Ce n'est pas obligatoire que ces clés soient les clés du modèle, même si c'est un cas typique.
3. descriptionProperty ou descriptionProperties : Propriété ou liste de propriétés à afficher dans la liste déroulante.
4. orderBykey : Si un tri doit être effectué, par défaut c'est selon les descriptions. Vous pouvez aussi utiliser un tri avec une clause SQL orderBy si vous en avez besoin.
5. readOnlyAsLabel : Si c'est en lecture seule, la propriété est affiché comme libellé. Par défaut la valeur est false (faux).
6. condition : Condition pour limiter les données à afficher. Cette option utilise une syntaxe SQL mais vous pouvez utiliser des noms de propriété entre ${} et les propriétés qualifiées sont disponibles. Vous pouvez également ajouter des arguments avec ? dans le cas où l'affichage d'une propriété dépend d'une autre et qu'un rafraîchissement des données doit être effectué après un changement de l'autre propriété.
7. parameterValuesStereotypes : Liste des stéréotypes dont les propriétés de l'éditeur dépendent. Cet attribut est utilisé pour affecter des valeurs aux arguments de propriété condition. Il correspond à l'attribut depends-stereotypes (12).
8. parameterValuesProperties : Liste des propriétés dont les propriétés de l'éditeur dépendent. Cet attribut est utilisé pour affecter des valeurs aux arguments de la propriété condition. Il correspond à l'attribut depends-properties (13).
9. descriptionFormatter : Formateur des descriptions affichées dans la liste déroulante. La classe déclarée doit implémenter l'interface IFormatter.

En suivant cet exemple, vous pouvez apprendre comment créer vos propres stéréotypes qui affichent une propriété simple dans une liste déroulante et avec des données dynamiques. Quoiqu'il en soit, dans la plupart des cas, il est plus pratique d'utiliser des références marquées avec l'annotation @DescriptionsList, mais le choix vous appartient toujours.

Vue JSP personnalisée et les taglibs OpenXava

Manifestement, la meilleure façon de créer des interface utilisateurs est d'utiliser les annotations expliquées au chapitre 4. Mais dans des cas extrêmes, vous devrez définir certaines vues avec du code JSP. OpenXava le permet. Et afin de vous aider, vous pouvez utiliser quelques taglibs JSP fournis par OpenXava. Voyons un exemple :

Exemple

Tout d'abord, vous devez définir que votre module utilise votre propre JSP dans le fichier application.xml :

<module name="SellersJSP" folder="invoicing.variations">
    <model name="Seller"/>
    <view name="ForCustomJSP"/>                           <!-- 1 -->
    <web-view url="custom-jsp/seller.jsp"/>               <!-- 2 -->
    <controller name="Typical"/>
</module>

En utilisant l'élément web-view (2) dans la définition de vore module, OpenXava utilise votre page JSP pour afficher le détail, au lieu de générer la vue automatiquement. En outre, vous pouvez définir une vue OpenXava avec l'élément view (1). Celle-ci est utilisée pour sa connaissance des événements à déclencher et les propriétés à récupérer. Si elle n'est pas spécifiée, ce sera la vue par défaut de l'entité qui sera utilisée. Toutefois, il est recommandé de créer une vue OpenXava explicite pour votre vue JSP personnalisée de manière à contrôler explicitement les événements, les propriétés, l'ordre de saisie, etc.. Vous pouvez placer vos JSP dans le dossier web/custom-jsp (ou un autre de votre choix) de votre projet. Voici un exemple :

<%@ include file="../xava/imports.jsp"%>
 
<table>
<tr>
    <td>Number: </td>
    <td>
        <xava:editor property="number"/>
    </td>
</tr>
<tr>
    <td>Name: </td>
    <td>
        <xava:editor property="name"/>
    </td>
</tr>
 
<tr>
    <td>Level: </td>
    <td>
        <xava:editor property="level.id"/>
        <xava:editor property="level.description"/>
    </td>
</tr>
</table>

Vous êtes libre de créer votre fichier JSP comme vous le souhaitez, mais il est pratique d'utiliser les taglibs OpenXava comme dans ce cas <xava:editor/> qui affiche l'éditeur le plus adapté à la propriété indiquée en utilisant l'objet de session xava_view (de type org.openxava.view.View) et par conséquence tous les contrôleurs OpenXava (y compris CRUD) fonctionnent.
Vous pouvez remarquer que les propriétés qualifiées sont permises (comme level.id ou level.description) (depuis v2.0.1). En plus, lors de l'initialisation, les propriétés level.id et level.description sont remplies avec les valeurs correspondantes. En effet, tous les comportements d'une vue OpenXava sont disponibles dans votre JSP si vous utilisez les taglibs OpenXava.

xava:editor

Le tag <xava:editor/> permet d'afficher l'éditeur (un contrôle HTML) de votre propriété de la même manière qu'OpenXava le fait lorsqu'il génère l'interface utilisateur automatiquement.

<xava:editor
    property="propertyName"            <!-- 1 -->
    editable="true|false"              <!-- 2  New in v2.0.1 -->
    throwPropertyChanged="true|false"  <!-- 3  New in v2.0.1 -->
/>

1. property (obligatoire) : La propriété du modèle associé au module courant.
2. editable (optionnel) (depuis v2.0.1). Force l'éditeur à être en mode édition, sinon la valeur par défaut appropriée est assumée.
3. throwPropertyChanged (optionnel) (depuis v2.0.1). Force l'éditeur de déclencher une événement de changement de propriété, sinon la la valeur par défaut appropriée est assumée.

Ce tag génère le code Javascript qui permet à votre vue de travailler de la même manière qu'une vue automatique. Les propriétés qualifiées (propriétés de références) sont utilisables (depuis v2.0.1).

xava:action, xava:link, xava:image, xava:button

Le tag <xava:action/> permet d'afficher une action (un bouton ou une image que l'utilisateur peut cliquer).

<xava:action action="controller.action" argv="argv"/>

L'attribut action indique l'action à exécuter et l'attribut argv (optionnel) permet de passer des valeurs à certaines propriétés de l'action avant son exécution. Un exemple :

<xava:action action="CRUD.save" argv="resetAfter=true"/>

Lorsque l'utilisateur clique sur cette action, celle-ci exécute l'action CRUD.save, après avoir assigner la valeur true à la propriété resetAfter de l'action. L'action sera affichée sous forme d'image si elle a une image associée. Sinon, l'affichage est un bouton. Si vous souhaitez déterminer le style de rendu, vous pouvez utiliser les taglibs suivants :<xava:button/>, <xava:image/> ou <xava:link/> similaires à <xava:action/>.
Vous pouvez spécifier une chaîne de caractère vide comme action (depuis v2.2.1) comme ici :

<xava:action action=""/>

Dans ce cas, le tag n'a pas d'effet et aucune erreur n'est produite. Cette fonction est utilie si vous remplissez le nom de l'action dynamiquement (c'est-à-dire via action=<%=monCode()%>) et que la valeur peut être vide dans certains cas.

xava:message (depuis v2.0.3)

Le tag <xava:message/> permet d'afficher un message dans l'HTML produit à partir des fichiers de ressources i18n d'OpenXava.

<xava:message key="message_key" param="messageParam" intParam="messageParam"/>

Le message est d'abord recherché dans les fichiers de ressources de votre projet (VotreProjet/i18n/VotreProjet-messages.properties) et s'il n'est pas trouvé là, la recherche s'effectue dans les messages par défaut d'OpenXava (OpenXava/i18n/Messages.properties).
Les attributs param et intParam sont optionnels. L'attribut intParam est utilisé lorsque la valeur à envoyer comme paramètre est de type int. Si vous utilisez Java 5, vous pouvez toutjours utiliser l'attribut param car il est automatiquement converti grâce à l'autoboxing.
Ce tag ne génère que le texte du message sans tags de format HTML. Un exemple :

<xava:message key="list_count" intParam="<%=totalSize%>"/>

xava:descriptionsList (depuis v2.0.3)

Le tag <xava:descriptionsList/> permet d'afficher une liste déroulante (un combo HTML) de votre référence, de la même manière que le fait OpenXava lorsqu'il génère l'interface utilisateur automatiquement.

<xava:descriptionsList
    reference="referenceName"  <!-- 1 -->
/>

1. reference (obligatoire). Une référence dans le modèle associé au module courant.

Ce tag génère le code JavaScript nécessaire pour que votre vue fonctionne de la même manière que si elle était automatique. Un exemple :

<tr>
    <td>Level: </td>
    <td>
        <xava:descriptionsList reference="level"/>
    </td>
</tr>

Dans ce cas la référence level (niveau) est une référence du modèle courant (par exemple Seller - vendeur). Une liste déroulante est affichée avec tous les niveaux disponibles.

Xava Properties Settings

Please, translate this section to French
The xava.properties file allows you to change the behavior of OpenXava for the whole application.

Property	Description	Default
E-Mailing
emailAsUserNameInPortal		false
smtpHost	Host for mail send through SMTP provider
smtpHostTrusted (new in v4.7)	if true a mail server with an expired certificate can be used	false
smtpPort	Port for mail send through SMTP provider
smtpUserId	User id for connecting to mail SMTP provider
smtpUserPassword	User password for connecting to the SMTP server
Persistence
defaultPersistenceUnit	Persistence unit to be used as default	default
jpaCodeInPOJOs		Depends on persistence provider
mapFacadeAsEJB		false
mapFacadeAutoCommit		false
persistenceProviderClass	Defines which class provides the persistence handling	org.openxava.model.impl.JPAPersistenceProvider
Labels, Messages and Locales
i18nWarnings		false
portletLocales	Locales for portlet generation and deployment	bg, ca, de, en, es, fr, in, it, ja, ko, nl, pl, pt, ru, sv, zh
Application and Controllers
defaultLabelFormat	Possibles values for defaultLabelFormat are: NORMAL, SMALL and NO_LABEL	NORMAL
defaultLabelStyle	It has defined: bold-label, italic-label. And you can define your own style.
defaultModeController (new in v4m5)	Possibles values for defaultModeController are Mode, DetailList, DetailOnly, ListOnly and SplitOnly; moreover your own custom controllers. If not specified, the default mode controller associated to the style is used	Mode
duplicateComponentWarnings	On encountering duplicate components like controllers or modules, warning messages are written to the log	true
failOnAnnotationMisuse	Throws error if properties, references or collections have non-applicable annotations	true
generateDefaultModules	If true it is not required to define modules in application.xml, OX generates the modules' information automatically	true
Styling
liferay6StyleClass (new in v4m6)	Style class compatible with liferay 6	org.openxava.web.style.Liferay6Style
liferay51StyleClass	Style class compatible with liferay 5.1	org.openxava.web.style.Liferay51Style
liferay41StyleClass	Style class compatible with liferay 4.1	org.openxava.web.style.Liferay41Style
liferay43StyleClass	Style class compatible with liferay 4.3	org.openxava.web.style.Liferay43Style
styleClass	Class that handles the default UI element class assignment. Provides a simple way of making OX compatible with portal's css classes	org.openxava.web.style.Liferay51Style
styleCSS	URL of CSS file that provides a visual UI style for out of portal OX applications	liferay51/css/everything_unpacked.css
webSpherePortal61StyleClass	Style class compatible with WebSphere Portal 6.1	org.openxava.web.style.WebSpherePortal61Style
Views and Layouts
alignedByColumns (new in v4.7.1)	If true all properties within views are displayed aligned by column same as using # on all views. Active only for default implementations of layoutParser & layoutPainter.	false
buttonsForNoImageActions	If true when an action has no image it uses a button for display it, else it uses a link.	false
layoutParser (new in v4.5)	Name of a layout parser class. Implemented layout parser: org.openxava.web.layout.impl.DefaultLayoutParser (BETA)
layoutPainter (new in v4.5)	Name of a layout painter class. Implemented layout painter: org.openxava.web.layout.impl.DefaultLayoutPainter (BETA)
maxSizeForTextEditor	On large text (String) properties limits the display size to this value	100
messagesOnTop (new in v4.5)	If true errors, warnings and messages are displayed at the top, if false they are displayed at the bottom	true
readOnlyAsLabel		false
showIconForViewReadOnly (new in v4.6)
showLabelsForToolBarActions (new in v4m6)	If false the toolbar shows only the action images, no text is displayed	true
Lists and Collections
addColumnsPageRowCount	Limits the number of selectable properties that can be added to the columns of lists and collections	100
customizeList (new in v4m5)	If false, list customization is disallowed	true
detailOnBottomInCollections		false
ignoreAccentsForStringArgumentsInConditions (new in v4m6)	If true it ignores accents to string arguments for conditions in list and collections	false
pageRowCount	Default number of objects to show in lists and collections	10
resizeColumns (new in v4m5)	If false, columns resizing is disabled	true
saveAndStayForCollections (new in v4m6)	If false, the save and stay button is hidden when adding elements to collections	true
showCountInList		true
showIconForViewReadOnly		true
showFilterByDefaultInList	If true filter is show by default for list on init. The user always have the option to show or hide the filter	true
showFilterByDefaultInCollections	If true filter is show by default for collections on init. The user always have the option to show or hide the filter	true
summationInList (new in v4.3)	If true, summary rows are shown at bottom of lists, under numerical columns. Users can manually turn on or off the totals at each column	true
tabAsEJB		false
toUpperForStringArgumentsInConditions	If true upper case conversions are applied to string arguments for conditions in list and collections. If true, also the searching using list or collections are more flexible (the user can use indistinctly upper or lower case) but can be slower in some databases (because they cannot use index)	true
filterOnChange (new in v4.8)	Filtering is done automatically when an option of a combo is chosen, without clicking on filter button	true
Help
helpInNewWindow (new in v4m5)	If true the help page is opened in a new window, if false, the help page is opened in the current window	true
helpPrefix (new in v4m5)	Help prefix for the help URL generation
helpSuffix (new in v4m5)	Help suffix for the help URL generation
FILE/ARCHIVO Stereotype
filePersistorClass	Defines which class provides the storing of attachments.	org.openxava.web.editors.FileSystemPersistor
filesPath	File storage directory, if no database is used.
Reporting
reportParametersProviderClass	class that provides the report parameters	org.openxava.util.DefaultReportParametersProvider
Miscelaneous
csvEncoding (new in v4.2.1)	Because it's impossible to obtain the client encoding, that used by Excel to open the file. UTF-8, ISO-8859-1
csvSeparator		;
hibernateJavaLoggingLevel	Logging level for hibernate. Valid values are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL, OFF	INFO
javaLoggingLevel	Logging level for java. Valid values are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL, OFF	INFO